deriveResponseStatus() does not implement the documented rule that a set response_skrivelse_id implies RESPONDED/PARTIAL. Right now, a record with gov_response_status: 'PENDING' but a non-null response_skrivelse_id will still return PENDING (or OVERDUE), which makes status derivation inconsistent with the data model and CLI updates. Consider deriving primarily from response_skrivelse_id (and optionally open_recommendations/explicit flag) rather than requiring the stored status to already be RESPONDED/PARTIAL.

Function name calculateSkrivelsDeadline appears to have a typo (“Skrivels” vs “Skrivelse”). Since this is a new public API, consider renaming to calculateSkrivelseDeadline (and optionally keeping the old name as a deprecated alias) to avoid cementing the misspelling across scripts/docs/tests.

fs is imported but never used, which will fail linting in this repo’s ESLint setup. Remove the unused import (or use node:fs via the injected read/write fns if you intended to rely on it).

parseArgs() accepts --date but does not validate it. If an invalid value is passed, asOf becomes Invalid Date and later opts.asOf.toISOString() will throw, producing a less actionable failure. Validate asOf (e.g., isNaN(asOf.getTime())) and exit with a clear error message when --date is invalid.

saveRirDataset() is invoked when alerts.length > 0 even if updatedCount === 0, but alert detection does not mutate the dataset. This will rewrite the JSON (and bump last_updated) on every run whenever any overdue item exists, creating noisy diffs/commits. Consider only saving when records actually change, or explicitly mutate stored statuses before saving if the intent is to persist derived OVERDUE state.

Test updates last_updated to today can be flaky around UTC midnight because it compares two separate new Date() calls (one inside saveRirDataset, one in the test). Use Vitest fake timers (vi.useFakeTimers() + vi.setSystemTime(...)) or inject a clock into saveRirDataset to make this deterministic.

newStatus is always set to 'RESPONDED' (the conditional expression returns 'RESPONDED' on both branches), which makes the comment about “PARTIAL → RESPONDED” misleading and leaves dead logic. Either simplify this assignment, or implement the intended branching (e.g., only upgrade PARTIAL when a newer/full response is detected).

PR description says the JSON Schema enforces that gov_response_status: "RESPONDED" requires a non-null response_skrivelse_id, but the schema currently has no conditional if/then (or similar) to enforce that relationship. Add a conditional schema rule (draft-07 supports if/then) to ensure CI validation matches the stated contract.

Constitutional citations are inconsistent across the newly added artifacts: this dataset note cites “RF 5:4 + RO 10:4”, while scripts/rir-followups-client.ts cites “RF ch. 13:7 + RO 10:4”. Align the references (or clarify why multiple provisions apply) so users don’t propagate conflicting constitutional bases into assessments.

JSDoc for calculateSkrivelsDeadline says “returned date is the last day of the 4th full calendar month”, but the implementation keeps the same day-of-month and only clamps to month-end when needed. Reword the description to match the actual rule (add N calendar months; clamp to month-end if target month is shorter).

parseArgs silently ignores --date when it is the last argument (no value provided). That can lead to running with today's date unexpectedly. Consider treating --date without a following value as a usage error (print message + exit 1/2).

fetchRiksdagSkrivelser hard-limits results to 50 (sz) and does not paginate. Over a 90-day window it’s plausible to exceed this and miss matching skrivelser, leaving records stuck as PENDING/OVERDUE. Consider paging through results until exhausted (or increasing sz and still paging as a safety net).

matchSkrivelse tries to match an already-recorded response_skrivelse_id by checking whether docId (dok_id/id) includes the stored value. In the dataset the field is a human reference like Skr. 2025/26:78, which won’t be contained in a dok_id like H.... Match against skrivelse.beteckning (or normalize both sides) instead, otherwise previously-responded records may never match.

When a matching skrivelse is found, the script always writes gov_response_status: 'RESPONDED' even if open_recommendations > 0. That conflicts with the library’s derivation rules (response + open recommendations => PARTIAL) and can persist an incorrect status to data/rir-followups.json. Consider deriving the stored status from open_recommendations (and/or preserving PARTIAL unless you have evidence the new skrivelse closes recommendations).

daysOverdue returns 0 for invalid deadlineDate / asOf values because Invalid Date produces NaN and diffMs > 0 becomes false. Since calculateSkrivelseDeadline throws on invalid input, consider validating here too (throw RangeError when either date is invalid) to avoid silently masking bad data.

detectOverdueAlerts defaults missing risk_level to MEDIUM, while filterByMinRiskLevel treats missing risk_level as LOW. Having two different defaults makes downstream logic harder to reason about (e.g., alerts vs. filtering). Consider using a single shared default (and ideally a constant) for missing risk.

JSDoc for loadRirDataset lists parameters in the opposite order of the actual function signature (it documents readFileFn before filePath). This can mislead callers and generated docs; please align the @param order/names with the signature.